<!DOCTYPE html>
<!--
     SPDX-License-Identifier: CC-BY-SA-4.0
     SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
-->
<!-- Page last generated 2025-02-20 03:16:15 +0000 -->
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Setting up your machine | seL4 docs</title>

    <!-- Our stylesheet and theme stylesheet.  Contains bootstrap. -->
    <link rel="stylesheet" href="/assets/css/style.css" type="text/css">
    <!-- Font awesome -->
    <link href="https://use.fontawesome.com/releases/v5.0.8/css/all.css" rel="stylesheet">
    <link href="https://fonts.googleapis.com/css2?family=Roboto&display=swap" rel="stylesheet">
    <!-- Pygments syntax highlighting  -->
    <link rel="stylesheet" href="/assets/css/highlighting/trac.css" type="text/css">
    <link rel="icon" type="image/x-icon" href="/assets/favicon.ico"><script defer data-domain="docs.sel4.systems"
	    src="https://analytics.sel4.systems/js/script.js"></script></head>

  <body class="container-fluid">

    



<header>
  <ul class="row menu">
    <li class="col-xs-12 col-md-2" >
            <a href="https://sel4.systems" class="skip-icon">
              <img class="img-responsive" src="/assets/logo-text-white.svg" alt="seL4 logo" />
            </a>
    </li>
    <li class="col-xs-12 col-md-10 menu">
      <nav aria-label="Banner links">
        <h2><a href="/Resources" />Resources</h2>
        <h2><a href="/processes" />Contributing</a></h2>
        <h2><a href="/projects" />Projects</h2>
        <h2><a href="/Tutorials" />Tutorials</h2>
        <iframe title="DuckDuckGo search bar" src="https://duckduckgo.com/search.html?site=docs.sel4.systems&prefill=Search%20sel4.systems" style="overflow:hidden;margin-bottom:10px; padding:0;height:40px;float:right;border-width: 0px"></iframe>
      </nav>
    </li>
  </ul>
  <div class="clear"></div>
  
<div class="breadcrumbs bootstrap hidden-sm-down">
  <nav class="sel-breadcrumb" aria-label="Breadcrumb" >
    <ol class=" list-unstyled" vocab="http://schema.org/" typeof="BreadcrumbList">
      
      
        

        

        <li class="breadcrumb-item" property="itemListElement" typeof="ListItem">
            <a property="item" typeof="WebPage" href="/">
              <span property="name"><b>seL4 Docs</b></span>
            </a>
            <meta property="position" content="1" />
        </li>
      
        

        

        <li class="breadcrumb-item" property="itemListElement" typeof="ListItem">
            <a property="item" typeof="WebPage" href="/Tutorials/">
              <span property="name"><b>Tutorials</b></span>
            </a>
            <meta property="position" content="2" />
        </li>
      
        

        
          <li class="breadcrumb-item" property="itemListElement" typeof="ListItem">
            <span property="name">Setting up your machine</span>
            <meta property="position" content="3" /></li>
          
    </ol>
  </nav>
  <nav class="sel-version" aria-label="Current Versions">
    <ol class="list-unstyled">
      <li class="list-unstyled text-right" style="margin-left:auto; padding:0rem 0rem;">
        Current versions:</li>
      <li class="list-unstyled text-right">
      <a href="/releases/sel4/13.0.0"><b>seL4-13.0.0</b></a></li>
      <li class="list-unstyled text-right">
      <a href="/releases/microkit/1.4.1"><b>microkit-1.4.1</b></a></li>
      <li class="list-unstyled text-right">
      <a href="/releases/camkes/camkes-3.11.0"><b>camkes-3.11.0</b></a></li>
      <li class="list-unstyled text-right">
      <a href="/releases/capdl/0.3.0"><b>capDL-0.3.0</b></a></li>
      </ol>
  </nav>
  <div class='clear'></div>
</div>


</header>

    <main>
      <div class="row">
  <div class="hidden-xs col-sm-4 col-md-3 col-lg-2">
    

<div class="sidebar">
  <ul class="nav nav-sidebar tutorial-sidebar">
    <li class="nav-section">Getting started</li>
      <li><a href="/Tutorials/">Overview</a></li>
      <li><a href="/Tutorials/pathways">Tutorial pathways</a></li>
    <li class="nav-section">seL4</li>
      <li><a href="/Tutorials/setting-up">Setting up your machine</a></li>
      <li><a href="/Tutorials/get-the-tutorials">Getting the tutorials</a></li>
      <li><a href="/Tutorials/hello-world">Hello world</a></li>
      <li><a href="/Tutorials/capabilities">Capabilities</a></li>
      <li><a href="/Tutorials/untyped">Untyped</a></li>
      <li><a href="/Tutorials/mapping">Mapping</a></li>
      <li><a href="/Tutorials/threads">Threads</a></li>
      <li><a href="/Tutorials/ipc">IPC</a></li>
      <li><a href="/Tutorials/notifications">Notifications</a></li>
      <li><a href="/Tutorials/interrupts">Interrupts</a></li>
      <li><a href="/Tutorials/fault-handlers">Fault handling</a></li>
      <li><a href="/Tutorials/mcs">MCS extensions</a></li>
    <li class="nav-section">C Libraries</li>
      <li><a href="/Tutorials/libraries-1">Initialisation &amp; threading</a></li>
      <li><a href="/Tutorials/libraries-2">IPC</a></li>
      <li><a href="/Tutorials/libraries-3">Processes &amp; Elf loading</a></li>
      <li><a href="/Tutorials/libraries-4">Timer</a></li>
    <li class="nav-section">Microkit</li>
      <li><a href="https://trustworthy.systems/projects/microkit/tutorial/">Tutorial</a></li>
    <li class="nav-section">CAmkES</li>
      <li><a href="/Tutorials/hello-camkes-0">Hello CAmkES</a></li>
      <li><a href="/Tutorials/hello-camkes-1">Introduction to CAmkES</a></li>
      <li><a href="/Tutorials/hello-camkes-2">Events in CAmkES</a></li>
      <li><a href="/Tutorials/hello-camkes-timer">CAmkES timer tutorial</a></li>
      <li><a href="/Tutorials/camkes-vm-linux">CAmkES VM</a></li>
      <li><a href="/Tutorials/camkes-vm-crossvm">CAmkES cross-VM connectors</a></li>
    <li class="nav-section">Rust</li>
      <li><a href="https://github.com/seL4/rust-sel4">GitHub</a></li>
    <li class="nav-section">Resources</li>
      <li><a href="https://sel4.systems/Info/Docs/seL4-manual-latest.pdf">seL4 Manual</a></li>
      <li><a href="/projects/sel4/api-doc.html">seL4 API reference</a></li>
      <li><a href="/Tutorials/how-to">How to: a quick solutions guide</a></li>
      <li><a href="/projects/sel4-tutorials/debugging-guide">Debugging guide</a></li>
      <li><a href="/Resources#contact">Help contacts</a></li>
  </ul>
</div>

  </div>
  <div class="content col-sm-8 col-md-6 col-lg-7 main">

    <h1 id="setting-up-your-machine">Setting up your machine</h1>

<h2 id="googles-repo-tool">Google’s Repo tool</h2>

<p>The primary way of obtaining and managing seL4 project sources is through the use of Google’s Repo tool.</p>

<p>To install run:</p>
<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code>  <span class="nb">sudo </span>apt-get update
  <span class="nb">sudo </span>apt-get <span class="nb">install </span>repo
</code></pre></div></div>

<details>
  <summary>More on Repo</summary>
  <p><br />
<a href="https://source.android.com/setup/develop#installing-repo">More details about on installing Repo</a>.</p>

  <p><a href="../projects/buildsystem/repo-cheatsheet">seL4 Repo cheatsheet</a></p>
</details>

<h2 id="docker">Docker</h2>
<p>To compile and use seL4, it is recommended that you use Docker to isolate the dependencies from your machine.</p>

<p>These instructions assume you are using Debian (or a derivative, such as Ubuntu), and are using Bash for your shell. However, it should be informative enough for users of other distros/shells to adapt.</p>

<p>These instructions are intended for Ubuntu LTS versions 20.04 and 22.04.</p>

<p>To begin, you will need at least these two programs:</p>

<ul>
  <li>make (<code class="language-plaintext highlighter-rouge">sudo apt install make</code>)</li>
  <li>docker (See <a href="https://get.docker.com">here</a> or <a href="https://docs.docker.com/engine/installation">here</a> for installation instructions)</li>
</ul>

<p>For convenience, add your account to the docker group:</p>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">sudo </span>usermod <span class="nt">-aG</span> docker <span class="si">$(</span><span class="nb">whoami</span><span class="si">)</span>
</code></pre></div></div>

<details>
  <summary>More on Docker</summary>
  <p><br /></p>

  <p><strong>Available images</strong></p>

  <p>All the prebuilt docker images are available on <a href="https://hub.docker.com/u/trustworthysystems">DockerHub here</a></p>

  <p>These images are used by the Trustworthy Systems Continuous Integration (CI) software, and so represent a standard software setup we use.
  The CI software always uses the <code class="language-plaintext highlighter-rouge">latest</code> docker image, but images are also tagged with the date they were built.</p>

  <p><strong>More information</strong></p>

  <p>You can find the dockerfiles and supporting Makefile <a href="https://github.com/seL4/seL4-CAmkES-L4v-dockerfiles">here</a></p>

</details>

<h3 id="getting-a-build-environment">Getting a build environment</h3>
<p>To get a running build environment for seL4 and CAmkES, run:</p>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git clone https://github.com/seL4/seL4-CAmkES-L4v-dockerfiles.git
<span class="nb">cd </span>seL4-CAmkES-L4v-dockerfiles
make user
</code></pre></div></div>

<p>This will give you a terminal inside a container that has all the relevant tools to build, simulate, and test seL4 &amp; Camkes programs.</p>

<p>The first time you run this, docker will fetch the relevant images, which may take a while.</p>

<p>The last line will say something like:</p>

<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Hello, welcome to the seL4/CAmkES/L4v docker build environment
</code></pre></div></div>

<h3 id="mapping-a-container">Mapping a container</h3>
<p>To run the container from other directories (e.g. starting a container for the <a href="/Tutorials/hello-world.html">Hello World</a> tutorial, which we’ll do next), you can setup a bash alias such as this:</p>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">echo</span> <span class="s1">$'alias container=</span><span class="se">\'</span><span class="s1">make -C /&lt;path&gt;/&lt;to&gt;/seL4-CAmkES-L4v-dockerfiles user HOST_DIR=$(pwd)</span><span class="se">\'</span><span class="s1">'</span> <span class="o">&gt;&gt;</span> ~/.bashrc
<span class="c"># now open a new terminal, or run `source ~/.bashrc`</span>
</code></pre></div></div>

<p>Replace <code class="language-plaintext highlighter-rouge">/&lt;path&gt;/&lt;to&gt;/</code> to match where you cloned the git repo of the docker files.</p>

<p><em>Reminder:</em> Include the absolute path to your <code class="language-plaintext highlighter-rouge">seL4-CAmkES-L4v-dockerfiles</code> folder, e.g.</p>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">echo</span> <span class="s1">$'alias container=</span><span class="se">\'</span><span class="s1">make -C /~/seL4-CAmkES-L4v-dockerfiles user HOST_DIR=$(pwd)</span><span class="se">\'</span><span class="s1">'</span> <span class="o">&gt;&gt;</span> ~/.bashrc
<span class="c"># now open a new terminal, or run `source ~/.bashrc`</span>

</code></pre></div></div>

<p>This then allows you to run <code class="language-plaintext highlighter-rouge">container</code> from any directory.</p>

<p><em>Reminder:</em> start a new terminal for the changes in <code class="language-plaintext highlighter-rouge">.bashrc</code> to take effect or run <code class="language-plaintext highlighter-rouge">source ~/.bashrc</code>.</p>

<h2 id="an-example-workflow">An example workflow</h2>

<p>A good workflow is to run two terminals:</p>

<ul>
  <li>Terminal A is just a normal terminal, and is used for git operations, editing (e.g., vim, emacs, vscode), and other non-build operations.</li>
  <li>Terminal B is running in a container, and is only used for compilation.</li>
</ul>

<p>This gives you the flexibility to use all the normal tools you are used to, while having the seL4 dependencies separated from your machine.</p>

<h3 id="compiling-sel4-test">Compiling seL4 test</h3>

<p>Start two terminals (terminal A and terminal B).</p>

<p>In terminal A, run these commands:</p>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>jblogs@host:~<span class="nv">$ </span><span class="nb">mkdir</span> ~/seL4test
jblogs@host:~<span class="nv">$ </span><span class="nb">cd</span> ~/seL4test
jblogs@host:~/seL4test<span class="nv">$ </span>repo init <span class="nt">-u</span> https://github.com/seL4/seL4test-manifest.git
jblogs@host:~/seL4test<span class="nv">$ </span>repo <span class="nb">sync</span>
</code></pre></div></div>

<p>In terminal B, run these commands:</p>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>jblogs@host:~<span class="nv">$ </span><span class="nb">cd</span> ~/seL4test
jblogs@host:~/seL4test<span class="nv">$ </span>container  <span class="c"># using the bash alias defined above</span>
jblogs@in-container:/host<span class="nv">$ </span><span class="nb">mkdir </span>build-x86
jblogs@in-container:/host<span class="nv">$ </span><span class="nb">cd </span>build-x86
jblogs@in-container:/host/build-x86<span class="nv">$ </span>../init-build.sh <span class="nt">-DPLATFORM</span><span class="o">=</span>x86_64 <span class="nt">-DSIMULATION</span><span class="o">=</span>TRUE
jblogs@in-container:/host/build-x86<span class="nv">$ </span>ninja
jblogs@in-container:/host/build-x86<span class="nv">$ </span>./simulate
</code></pre></div></div>

<p>If you need to make any code modifications or commit things to git, use terminal A. If you need to recompile or simulate an image, use terminal B.</p>

<p><code class="language-plaintext highlighter-rouge">./simulate</code> is run using <a href="https://www.qemu.org/">QEMU</a>, and will take a few minutes to run. If QEMU works, you’ll see something like</p>

<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Test suite passed. 121 tests passed. 57 tests disabled.
All is well in the universe
</code></pre></div></div>

<p>Note, if QEMU fails when trying to simulate the image, try configuring your Docker host to give the container more memory using <a href="https://docs.docker.com/desktop/use-desktop/">Docker Desktop</a>.</p>

<p>That’s it! seL4 is running.</p>

<p>To quit QEMU: <code class="language-plaintext highlighter-rouge">Ctrl+a, x</code></p>


<p style="text-align: right;">

      Next: <a href="/Tutorials/get-the-tutorials">Getting the tutorials</a>
</p>


  </div>

  
    
<div class="sidebar-toc hidden-xs hidden-sm col-md-3 col-lg-3">
    <ul id="toc" class="section-nav">
<li class="toc-entry toc-h2"><a href="#googles-repo-tool">Google’s Repo tool</a></li>
<li class="toc-entry toc-h2"><a href="#docker">Docker</a>
<ul>
<li class="toc-entry toc-h3"><a href="#getting-a-build-environment">Getting a build environment</a></li>
<li class="toc-entry toc-h3"><a href="#mapping-a-container">Mapping a container</a></li>
</ul>
</li>
<li class="toc-entry toc-h2"><a href="#an-example-workflow">An example workflow</a>
<ul>
<li class="toc-entry toc-h3"><a href="#compiling-sel4-test">Compiling seL4 test</a></li>
</ul>
</li>
</ul>
</div>

  
</div>
<script src="/assets/js/toggle-markdown.js"></script>

    </main>
    


<footer class="site-footer">

  <h2 class="footer-heading">seL4 docs</h2>

  <div class="footer-col-wrapper">

    <div class="col-md-2">
      



<ul class="social-media-list">
  <li><a href="https://github.com/sel4"><i class="fab fa-github"></i> <span class="username">sel4</span></a></li><li><a href="https://github.com/sel4proj"><i class="fab fa-github"></i> <span class="username">sel4proj</span></a></li>
</ul>

    </div>

    <div class="col-md-8">
      <ul class="list-unstyled">
        <li>
          This site is for displaying seL4 related documentation.  Pull requests are welcome.
        </li>
        
          <li>
            Site last updated: Fri Feb 7 10:17:38 2025 +1100 ee78c8857c
          </li>
          <li>
                Page last updated: Mon Jan 6 18:52:01 2025 +1100 df31e5ccb8
          </li>
        
      </ul>
    </div>
    <div class="col-md-2">
<a href="https://github.com/seL4/docs/blob/master/Tutorials/setting-up.md">View page on GitHub</a>
      <br />
      <a href="https://github.com/seL4/docs/edit/master/Tutorials/setting-up.md">Edit page on GitHub</a>
      <br />
      <a href="/sitemap">Sitemap</a>
    </div>

  </div>

</footer>

  </body>
</html>
